home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / gutenprint / curve.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-03-15  |  25.4 KB  |  687 lines
  1. /*
  2.  * "$Id: curve.h,v 1.1 2004/09/17 18:38:01 rleigh Exp $"
  3.  *
  4.  *   libgimpprint curve functions.
  5.  *
  6.  *   Copyright 1997-2000 Michael Sweet (mike@easysw.com) and
  7.  *    Robert Krawitz (rlk@alum.mit.edu)
  8.  *
  9.  *   This program is free software; you can redistribute it and/or modify it
  10.  *   under the terms of the GNU General Public License as published by the Free
  11.  *   Software Foundation; either version 2 of the License, or (at your option)
  12.  *   any later version.
  13.  *
  14.  *   This program is distributed in the hope that it will be useful, but
  15.  *   WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  16.  *   or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  17.  *   for more details.
  18.  *
  19.  *   You should have received a copy of the GNU General Public License
  20.  *   along with this program; if not, write to the Free Software
  21.  *   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  22.  */
  23.  
  24. /**
  25.  * @file gutenprint/curve.h
  26.  * @brief Curve functions.
  27.  */
  28.  
  29. #ifndef GUTENPRINT_CURVE_H
  30. #define GUTENPRINT_CURVE_H
  31.  
  32. #include <stdio.h>
  33. #include <stdlib.h>
  34.  
  35. #include <gutenprint/sequence.h>
  36.  
  37. #ifdef __cplusplus
  38. extern "C" {
  39. #endif
  40.  
  41.  
  42.   /*
  43.    * Curve code borrowed from GTK+, http://www.gtk.org/
  44.    */
  45.  
  46.   /**
  47.    * The curve type models a linear, spline or gamma curve.  curve
  48.    * "inherits" from the sequence data structure (implemented via
  49.    * containment), since the curve data is represented internally as a
  50.    * sequence of numbers, for linear and spline curves.  Linear
  51.    * Piecewise Curves (LPCs) should be implemented in the future which
  52.    * represent a curve in a more compact format.
  53.    *
  54.    * Various operations are supported, including interpolation and
  55.    * composition.
  56.    *
  57.    * @defgroup curve curve
  58.    * @{
  59.    */
  60.  
  61. struct stp_curve;
  62.   /** The curve opaque data type. */
  63. typedef struct stp_curve stp_curve_t;
  64.  
  65.   /** Curve types. */
  66. typedef enum
  67. {
  68.   /** Linear interpolation. */
  69.   STP_CURVE_TYPE_LINEAR,
  70.   /** Spline interpolation. */
  71.   STP_CURVE_TYPE_SPLINE
  72. } stp_curve_type_t;
  73.  
  74.   /** Wrapping mode. */
  75. typedef enum
  76. {
  77.   /** The curve does not wrap */
  78.   STP_CURVE_WRAP_NONE,
  79.   /** The curve wraps to its starting point. */
  80.   STP_CURVE_WRAP_AROUND
  81. } stp_curve_wrap_mode_t;
  82.  
  83.   /** Composition types. */
  84. typedef enum
  85. {
  86.   /** Add composition. */
  87.   STP_CURVE_COMPOSE_ADD,
  88.   /** Multiply composition. */
  89.   STP_CURVE_COMPOSE_MULTIPLY,
  90.   /** Exponentiate composition. */
  91.   STP_CURVE_COMPOSE_EXPONENTIATE
  92. } stp_curve_compose_t;
  93.  
  94.   /** Behaviour when curve exceeds bounds. */
  95. typedef enum
  96. {
  97.   /** Rescale the bounds. */
  98.   STP_CURVE_BOUNDS_RESCALE,
  99.   /** Clip the curve to the existing bounds. */
  100.   STP_CURVE_BOUNDS_CLIP,
  101.   /** Error if bounds are violated. */
  102.   STP_CURVE_BOUNDS_ERROR
  103. } stp_curve_bounds_t;
  104.  
  105.   /** Point (x,y) for piecewise curve. */
  106. typedef struct
  107. {
  108.   /** Horizontal position. */
  109.   double x;
  110.   /** Vertical position. */
  111.   double y;
  112. } stp_curve_point_t;
  113.  
  114. /**
  115.  * Create a new curve.  Curves have y=lower..upper.  The default
  116.  * bounds are 0..1.  The default interpolation type is linear.  There
  117.  * are no points allocated, and the gamma is defaulted to 1.  The curve
  118.  * is a dense (equally-spaced) curve.
  119.  *
  120.  * A wrapped curve has the same value at x=0 and x=1.  The wrap mode
  121.  * of a curve cannot be changed except by routines that destroy the
  122.  * old curve entirely (e. g. stp_curve_copy, stp_curve_read).
  123.  * @param wrap the wrap mode of the curve.
  124.  * @returns the newly created curve.
  125.  */
  126. extern stp_curve_t *stp_curve_create(stp_curve_wrap_mode_t wrap);
  127.  
  128.   /**
  129.    * Copy and allocate an curve.
  130.    * dest will be created, and then the contents of source will be
  131.    * copied into it.  dest must not have been previously allocated
  132.    * with stp_curve_create().
  133.    * @param curve the source curve.
  134.    * @returns the new copy of the curve.
  135.    */
  136. extern stp_curve_t *stp_curve_create_copy(const stp_curve_t *curve);
  137.  
  138.   /**
  139.    * Copy an curve.
  140.    * Both dest and source must be valid curves previously created with
  141.    * stp_curve_create().
  142.    * @param dest the destination curve.
  143.    * @param source the source curve.
  144.    */
  145. extern void stp_curve_copy(stp_curve_t *dest, const stp_curve_t *source);
  146.  
  147.   /**
  148.    * Destroy an curve.
  149.    * It is an error to destroy the curve more than once.
  150.    * @param curve the curve to destroy.
  151.    */
  152. extern void stp_curve_destroy(stp_curve_t *curve);
  153.  
  154. /**
  155.  * Set the lower and upper bounds on a curve.
  156.  * To change the bounds adjusting data as required, use
  157.  * stp_curve_rescale instead.
  158.  * @param curve the curve to use.
  159.  * @param low the lower bound.
  160.  * @param high the upper bound.
  161.  * @returns FALSE if any existing points on the curve are outside the
  162.  * bounds.
  163.  */
  164. extern int stp_curve_set_bounds(stp_curve_t *curve, double low, double high);
  165.  
  166. /**
  167.  * Get the lower and upper bounds on a curve.
  168.  * @param curve the curve to use.
  169.  * @param low a pointer to a double to store the lower bound in.
  170.  * @param high a pointer to a double to store the upper bound in.
  171.  */
  172. extern void stp_curve_get_bounds(const stp_curve_t *curve,
  173.                  double *low, double *high);
  174.  
  175. /**
  176.  * Get the wrapping mode.
  177.  * @param curve the curve to use.
  178.  * @returns the wrapping mode.
  179.  */
  180. extern stp_curve_wrap_mode_t stp_curve_get_wrap(const stp_curve_t *curve);
  181.  
  182. /**
  183.  * Determine whether the curve is piecewise
  184.  * @param curve the curve to use.
  185.  * @returns whether the curve is piecewise
  186.  */
  187. extern int stp_curve_is_piecewise(const stp_curve_t *curve);
  188.  
  189. /*
  190.  * Get the range (lowest and highest value of points) in the curve.
  191.  * This does not account for any interpolation that may place
  192.  * intermediate points outside of the curve.
  193.  * @param curve the curve to use.
  194.  * @param low a pointer to double to store the lower limit in.
  195.  * @param high a pointer to double to store the upper limit in.
  196.  */
  197. extern void stp_curve_get_range(const stp_curve_t *curve,
  198.                 double *low, double *high);
  199.  
  200. /**
  201.  * Get the number of allocated points in the curve.
  202.  * @param curve the curve to use.
  203.  * @returns the number of points.
  204.  */
  205. extern size_t stp_curve_count_points(const stp_curve_t *curve);
  206.  
  207. /**
  208.  * Set the curve interpolation type.
  209.  * @param curve the curve to use.
  210.  * @param itype the interpolation type.
  211.  * @returns 1 on success, or 0 if itype is invalid.
  212.  */
  213. extern int stp_curve_set_interpolation_type(stp_curve_t *curve,
  214.                         stp_curve_type_t itype);
  215.  
  216. /**
  217.  * Get the curve interpolation type.
  218.  * @param curve the curve to use.
  219.  * @returns the interpolation type.
  220.  */
  221. extern stp_curve_type_t stp_curve_get_interpolation_type(const stp_curve_t *curve);
  222.  
  223. /**
  224.  * Set all data points of the curve.  If any of the data points fall
  225.  * outside the bounds, the operation is not performed and FALSE is
  226.  * returned.  This creates a curve with equally-spaced points.
  227.  * @param curve the curve to use.
  228.  * @param count the number of points (must be at least two and not
  229.  * more than 1048576).
  230.  * @param data a pointer to an array of doubles (must be at least
  231.  * count in size).
  232.  * @returns 1 on success, 0 on failure.
  233.  */
  234. extern int stp_curve_set_data(stp_curve_t *curve, size_t count,
  235.                   const double *data);
  236.  
  237. /**
  238.  * Set all data points of the curve.  If any of the data points fall
  239.  * outside the bounds, the operation is not performed and FALSE is
  240.  * returned.  This creates a piecewise curve.
  241.  * @param curve the curve to use.
  242.  * @param count the number of points (must be at least two and not
  243.  * more than 1048576).
  244.  * @param data a pointer to an array of points (must be at least
  245.  * count in size).  The first point must have X=0, and each point must
  246.  * have an X value at least .000001 greater than the previous point.  If
  247.  * the curve is not a wraparound curve, the last point must have X=1.
  248.  * @returns 1 on success, 0 on failure.
  249.  */
  250. extern int stp_curve_set_data_points(stp_curve_t *curve, size_t count,
  251.                      const stp_curve_point_t *data);
  252.  
  253. /**
  254.  * Set the data points in a curve from float values.  If any of the
  255.  * data points fall outside the bounds, the operation is not performed
  256.  * and FALSE is returned.  This creates a curve with equally-spaced points.
  257.  * @param curve the curve to use.
  258.  * @param count the number of the number of points (must be at least
  259.  * two and not more than 1048576).
  260.  * @param data a pointer to an array of floats (must be at least
  261.  * count in size).
  262.  * @returns 1 on success, 0 on failure.
  263.  */
  264. extern int stp_curve_set_float_data(stp_curve_t *curve,
  265.                     size_t count, const float *data);
  266.  
  267. /**
  268.  * Set the data points in a curve from long values.  If any of the
  269.  * data points fall outside the bounds, the operation is not performed
  270.  * and FALSE is returned.  This creates a curve with equally-spaced points.
  271.  * @param curve the curve to use.
  272.  * @param count the number of the number of points (must be at least
  273.  * two and not more than 1048576).
  274.  * @param data a pointer to an array of longs (must be at least
  275.  * count in size).
  276.  * @returns 1 on success, 0 on failure.
  277.  */
  278. extern int stp_curve_set_long_data(stp_curve_t *curve,
  279.                    size_t count, const long *data);
  280.  
  281. /**
  282.  * Set the data points in a curve from unsigned long values.  If any
  283.  * of the data points fall outside the bounds, the operation is not
  284.  * performed and FALSE is returned.  This creates a curve with
  285.  * equally-spaced points.
  286.  * @param curve the curve to use.
  287.  * @param count the number of the number of points (must be at least
  288.  * two and not more than 1048576).
  289.  * @param data a pointer to an array of unsigned longs (must be at
  290.  * least count in size).
  291.  * @returns 1 on success, 0 on failure.
  292.  */
  293. extern int stp_curve_set_ulong_data(stp_curve_t *curve,
  294.                     size_t count, const unsigned long *data);
  295.  
  296. /**
  297.  * Set the data points in a curve from integer values.  If any of the
  298.  * data points fall outside the bounds, the operation is not performed
  299.  * and FALSE is returned.  This creates a curve with equally-spaced points.
  300.  * @param curve the curve to use.
  301.  * @param count the number of the number of points (must be at least
  302.  * two and not more than 1048576).
  303.  * @param data a pointer to an array of integers (must be at least
  304.  * count in size).
  305.  * @returns 1 on success, 0 on failure.
  306.  */
  307. extern int stp_curve_set_int_data(stp_curve_t *curve,
  308.                   size_t count, const int *data);
  309.  
  310. /**
  311.  * Set the data points in a curve from unsigned integer values.  If
  312.  * any of the data points fall outside the bounds, the operation is
  313.  * not performed and FALSE is returned.  This creates a curve with
  314.  * equally-spaced points.
  315.  * @param curve the curve to use.
  316.  * @param count the number of the number of points (must be at least
  317.  * two and not more than 1048576).
  318.  * @param data a pointer to an array of unsigned integers (must be at
  319.  * least count in size).
  320.  * @returns 1 on success, 0 on failure.
  321.  */
  322. extern int stp_curve_set_uint_data(stp_curve_t *curve,
  323.                    size_t count, const unsigned int *data);
  324.  
  325. /**
  326.  * Set the data points in a curve from short values.  If any of the
  327.  * data points fall outside the bounds, the operation is not performed
  328.  * and FALSE is returned.  This creates a curve with equally-spaced points.
  329.  * @param curve the curve to use.
  330.  * @param count the number of the number of points (must be at least
  331.  * two and not more than 1048576).
  332.  * @param data a pointer to an array of shorts (must be at least
  333.  * count in size).
  334.  * @returns 1 on success, 0 on failure.
  335.  */
  336. extern int stp_curve_set_short_data(stp_curve_t *curve,
  337.                     size_t count, const short *data);
  338.  
  339. /**
  340.  * Set the data points in a curve from unsigned short values.  If any
  341.  * of the data points fall outside the bounds, the operation is not
  342.  * performed and FALSE is returned.  This creates a curve with
  343.  * equally-spaced points.
  344.  * @param curve the curve to use.
  345.  * @param count the number of the number of points (must be at least
  346.  * two and not more than 1048576).
  347.  * @param data a pointer to an array of unsigned shorts (must be at
  348.  * least count in size).
  349.  * @returns 1 on success, 0 on failure.
  350.  */
  351. extern int stp_curve_set_ushort_data(stp_curve_t *curve,
  352.                      size_t count, const unsigned short *data);
  353.  
  354. /**
  355.  * Get a curve containing a subrange of data.  If the start or count
  356.  * is invalid, the returned curve will compare equal to NULL (i. e. it
  357.  * will be a null pointer).  start and count must not exceed the
  358.  * number of points in the curve, and count must be at least 2.
  359.  * The curve must be a dense (equally-spaced) curve
  360.  * @param curve the curve to use.
  361.  * @param start the start of the subrange.
  362.  * @param count the number of point starting at start.
  363.  * @returns a curve containing the subrange.  The returned curve is
  364.  * non-wrapping.
  365.  */
  366. extern stp_curve_t *stp_curve_get_subrange(const stp_curve_t *curve,
  367.                        size_t start, size_t count);
  368.  
  369. /*
  370.  * Set part of a curve to the range in another curve.  The data in the
  371.  * range must fit within both the bounds and the number of points in
  372.  * the first curve.  The curve must be a dense (equally-spaced) curve.
  373.  * @param curve the curve to use (destination).
  374.  * @param range the source curve.
  375.  * @param start the starting point in the destination range.
  376.  * @param returns 1 on success, 0 on failure.
  377.  */
  378. extern int stp_curve_set_subrange(stp_curve_t *curve, const stp_curve_t *range,
  379.                   size_t start);
  380.  
  381. /**
  382.  * Get a pointer to the curve's raw data.
  383.  * @param curve the curve to use.
  384.  * @param count a pointer to a size_t to store the curve size in.
  385.  * @returns a pointer to the curve data.  This data is not guaranteed
  386.  * to be valid beyond the next non-const curve call.  If the curve is
  387.  * a pure gamma curve (no associated points), NULL is returned and the
  388.  * count is 0.  This call also returns NULL if the curve is a piecewise
  389.  * curve.
  390.  */
  391. extern const double *stp_curve_get_data(const stp_curve_t *curve, size_t *count);
  392.  
  393. /**
  394.  * Get a pointer to the curve's raw data as points.
  395.  * @param curve the curve to use.
  396.  * @param count a pointer to a size_t to store the curve size in.
  397.  * @returns a pointer to the curve data.  This data is not guaranteed
  398.  * to be valid beyond the next non-const curve call.  If the curve is
  399.  * a pure gamma curve (no associated points), NULL is returned and the
  400.  * count is 0.  This call also returns NULL if the curve is a dense
  401.  * (equally-spaced) curve.
  402.  */
  403. extern const stp_curve_point_t *stp_curve_get_data_points(const stp_curve_t *curve, size_t *count);
  404.  
  405.  
  406. /**
  407.  * Get pointer to the curve's raw data as floats.
  408.  * @param curve the curve to use.
  409.  * @param count a pointer to a size_t to store the curve size in.
  410.  * @returns a pointer to the curve data.  This data is not guaranteed
  411.  * to be valid beyond the next non-const curve call.  If the curve is
  412.  * a pure gamma curve (no associated points), NULL is returned and the
  413.  * count is 0.  This also returns NULL if the curve is a piecewise curve.
  414.  */
  415. extern const float *stp_curve_get_float_data(const stp_curve_t *curve,
  416.                          size_t *count);
  417.  
  418. /**
  419.  * Get pointer to the curve's raw data as longs.
  420.  * @param curve the curve to use.
  421.  * @param count a pointer to a size_t to store the curve size in.
  422.  * @returns a pointer to the curve data.  This data is not guaranteed
  423.  * to be valid beyond the next non-const curve call.  If the curve is
  424.  * a pure gamma curve (no associated points), NULL is returned and the
  425.  * count is 0.  This also returns NULL if the curve is a piecewise curve.
  426.  */
  427. extern const long *stp_curve_get_long_data(const stp_curve_t *curve,
  428.                        size_t *count);
  429.  
  430. /**
  431.  * Get pointer to the curve's raw data as unsigned longs.
  432.  * @param curve the curve to use.
  433.  * @param count a pointer to a size_t to store the curve size in.
  434.  * @returns a pointer to the curve data.  This data is not guaranteed
  435.  * to be valid beyond the next non-const curve call.  If the curve is
  436.  * a pure gamma curve (no associated points), NULL is returned and the
  437.  * count is 0.  This also returns NULL if the curve is a piecewise curve.
  438.  */
  439. extern const unsigned long *stp_curve_get_ulong_data(const stp_curve_t *curve,
  440.                              size_t *count);
  441.  
  442. /**
  443.  * Get pointer to the curve's raw data as integers.
  444.  * @param curve the curve to use.
  445.  * @param count a pointer to a size_t to store the curve size in.
  446.  * @returns a pointer to the curve data.  This data is not guaranteed
  447.  * to be valid beyond the next non-const curve call.  If the curve is
  448.  * a pure gamma curve (no associated points), NULL is returned and the
  449.  * count is 0.  This also returns NULL if the curve is a piecewise curve.
  450.  */
  451. extern const int *stp_curve_get_int_data(const stp_curve_t *curve,
  452.                      size_t *count);
  453.  
  454. /**
  455.  * Get pointer to the curve's raw data as unsigned integers.
  456.  * @param curve the curve to use.
  457.  * @param count a pointer to a size_t to store the curve size in.
  458.  * @returns a pointer to the curve data.  This data is not guaranteed
  459.  * to be valid beyond the next non-const curve call.  If the curve is
  460.  * a pure gamma curve (no associated points), NULL is returned and the
  461.  * count is 0.  This also returns NULL if the curve is a piecewise curve.
  462.  */
  463. extern const unsigned int *stp_curve_get_uint_data(const stp_curve_t *curve,
  464.                            size_t *count);
  465.  
  466. /**
  467.  * Get pointer to the curve's raw data as shorts.
  468.  * @param curve the curve to use.
  469.  * @param count a pointer to a size_t to store the curve size in.
  470.  * @returns a pointer to the curve data.  This data is not guaranteed
  471.  * to be valid beyond the next non-const curve call.  If the curve is
  472.  * a pure gamma curve (no associated points), NULL is returned and the
  473.  * count is 0.  This also returns NULL if the curve is a piecewise curve.
  474.  */
  475. extern const short *stp_curve_get_short_data(const stp_curve_t *curve,
  476.                          size_t *count);
  477.  
  478. /**
  479.  * Get pointer to the curve's raw data as unsigned shorts.
  480.  * @param curve the curve to use.
  481.  * @param count a pointer to a size_t to store the curve size in.
  482.  * @returns a pointer to the curve data.  This data is not guaranteed
  483.  * to be valid beyond the next non-const curve call.  If the curve is
  484.  * a pure gamma curve (no associated points), NULL is returned and the
  485.  * count is 0.  This also returns NULL if the curve is a piecewise curve.
  486.  */
  487. extern const unsigned short *stp_curve_get_ushort_data(const stp_curve_t *curve,
  488.                                size_t *count);
  489.  
  490. /**
  491.  * Get the underlying stp_sequence_t data structure which stp_curve_t
  492.  * is derived from.
  493.  * This can be used for fast access to the raw data.
  494.  * @param curve the curve to use.
  495.  * @returns the stp_sequence_t.  If the curve is a piecewise curve, the
  496.  * sequence returned is NULL;
  497.  */
  498. extern const stp_sequence_t *stp_curve_get_sequence(const stp_curve_t *curve);
  499.  
  500. /**
  501.  * Set the gamma of a curve.  This replaces all existing points along
  502.  * the curve.  The bounds are set to 0..1.  If the gamma value is
  503.  * positive, the function is increasing; if negative, the function is
  504.  * decreasing.  Count must be either 0 or at least 2.  If the count is
  505.  * zero, the gamma of the curve is set for interpolation purposes, but
  506.  * points cannot be assigned to.  It is illegal to set gamma on a
  507.  * wrap-mode curve.  The resulting curve is treated as a dense
  508.  * (equally-spaced) curve.
  509.  * @param curve the curve to use.
  510.  * @param f_gamma the gamma value to set.
  511.  * @returns FALSE if the gamma value is illegal (0, infinity, or NaN),
  512.  * or if the curve wraps around.
  513.  */
  514. extern int stp_curve_set_gamma(stp_curve_t *curve, double f_gamma);
  515.  
  516. /**
  517.  * Get the gamma value of the curve.
  518.  * @returns the gamma value.  A value of 0 indicates that the curve
  519.  * does not have a valid gamma value.
  520.  */
  521. extern double stp_curve_get_gamma(const stp_curve_t *curve);
  522.  
  523. /**
  524.  * Set a point along the curve.
  525.  * This call destroys any gamma value assigned to the curve.
  526.  * @param curve the curve to use.
  527.  * @param where the point to set.
  528.  * @param data the value to set where to.
  529.  * @returns FALSE if data is outside the valid bounds or if where is
  530.  * outside the number of valid points.  This also returns NULL if
  531.  * the curve is a piecewise curve.
  532.  */
  533. extern int stp_curve_set_point(stp_curve_t *curve, size_t where, double data);
  534.  
  535. /**
  536.  * Get a point along the curve.
  537.  * @param curve the curve to use.
  538.  * @param where the point to get.
  539.  * @param data a pointer to a double to store the value of where in.
  540.  * @returns FALSE if where is outside of the number of valid
  541.  * points.  This also returns NULL if the curve is a piecewise curve.
  542.  */
  543. extern int stp_curve_get_point(const stp_curve_t *curve, size_t where,
  544.                    double *data);
  545.  
  546. /**
  547.  * Interpolate a point along the curve.
  548.  * @param curve the curve to use.
  549.  * @param where the point to interpolate.
  550.  * @param result a pointer to double to store the value of where in.
  551.  * If interpolation would produce a value outside of the allowed range
  552.  * (as could happen with spline interpolation), the value is clipped
  553.  * to the range.
  554.  * @returns FALSE if 'where' is less than 0 or greater than the number
  555.  * of points, an error is returned.  Also returns FALSE if the curve
  556.  * is a piecewise curve.
  557.  */
  558. extern int stp_curve_interpolate_value(const stp_curve_t *curve,
  559.                        double where, double *result);
  560.  
  561. /**
  562.  * Resample a curve (change the number of points).  This does not
  563.  * destroy the gamma value of a curve.  Points are interpolated as
  564.  * required; any interpolation that would place points outside of the
  565.  * bounds of the curve will be clipped to the bounds.  The resulting
  566.  * curve is always dense (equally-spaced).  This is the correct way
  567.  * to convert a piecewise curve to an equally-spaced curve.
  568.  * @param curve the curve to use (must not exceed 1048576).
  569.  * @param points the number of points.
  570.  * @returns FALSE if the number of points is invalid (less than two,
  571.  * except that zero points is permitted for a gamma curve).
  572.  */
  573. extern int stp_curve_resample(stp_curve_t *curve, size_t points);
  574.  
  575. /**
  576.  * Rescale a curve (multiply all points by a scaling constant).  This
  577.  * also rescales the bounds.  Note that this currently destroys the
  578.  * gamma property of the curve.
  579.  * @param curve the curve to use.
  580.  * @param scale the scaling factor.
  581.  * @param mode the composition mode.
  582.  * @param bounds_mode the bounds exceeding mode.
  583.  * @returns FALSE if this would exceed floating point limits
  584.  */
  585. extern int stp_curve_rescale(stp_curve_t *curve, double scale,
  586.                  stp_curve_compose_t mode,
  587.                  stp_curve_bounds_t bounds_mode);
  588.  
  589. /**
  590.  * Write a curve to a file.
  591.  * The printable representation is guaranteed to contain only 7-bit
  592.  * printable ASCII characters, and is null-terminated.  The curve will
  593.  * not contain any space, newline, single quote, or comma characters.
  594.  * Furthermore, a printed curve will be read back correctly in all locales.
  595.  * These calls are not guaranteed to provide more than 6 decimal places
  596.  * of precision or +/-0.5e-6 accuracy, whichever is less.
  597.  * @warning NOTE that these calls are not thread-safe!  These
  598.  * routines may manipulate the locale to achieve a safe
  599.  * representation.
  600.  * @param file the file to write.
  601.  * @param curve the curve to use.
  602.  * @returns 1 on success, 0 on failure.
  603.  */
  604. extern int stp_curve_write(FILE *file, const stp_curve_t *curve);
  605.  
  606. /**
  607.  * Write a curve to a string.
  608.  * The printable representation is guaranteed to contain only 7-bit
  609.  * printable ASCII characters, and is null-terminated.  The curve will
  610.  * not contain any space, newline, or comma characters.  Furthermore,
  611.  * a printed curve will be read back correctly in all locales.
  612.  * These calls are not guaranteed to provide more than 6 decimal places
  613.  * of precision or +/-0.5e-6 accuracy, whichever is less.
  614.  * @warning NOTE that these calls are not thread-safe!  These
  615.  * routines may manipulate the locale to achieve a safe
  616.  * representation.
  617.  * @param curve the curve to use.
  618.  * @returns a pointer to a string.  This is allocated on the heap, and
  619.  * it is the caller's responsibility to free it.
  620.  */
  621. extern char *stp_curve_write_string(const stp_curve_t *curve);
  622.  
  623. /**
  624.  * Create a curve from a stream.
  625.  * @warning NOTE that these calls are not thread-safe!  These
  626.  * routines may manipulate the locale to achieve a safe
  627.  * representation.
  628.  * @param fp the stream to read.
  629.  * @returns the newly created curve, or NULL if an error occured.
  630.  */
  631. extern stp_curve_t *stp_curve_create_from_stream(FILE* fp);
  632.  
  633. /**
  634.  * Create a curve from a stream.
  635.  * @warning NOTE that these calls are not thread-safe!  These
  636.  * routines may manipulate the locale to achieve a safe
  637.  * representation.
  638.  * @param file the file to read.
  639.  * @returns the newly created curve, or NULL if an error occured.
  640.  */
  641. extern stp_curve_t *stp_curve_create_from_file(const char* file);
  642.  
  643. /**
  644.  * Create a curve from a string.
  645.  * @warning NOTE that these calls are not thread-safe!  These
  646.  * routines may manipulate the locale to achieve a safe
  647.  * representation.
  648.  * @param string the string to read.
  649.  * @returns the newly created curve, or NULL if an error occured.
  650.  */
  651. extern stp_curve_t *stp_curve_create_from_string(const char* string);
  652.  
  653. /**
  654.  * Compose two curves, creating a third curve.  Only add and multiply
  655.  * composition is currently supported.
  656.  * If both curves are gamma curves with the same sign, and the
  657.  * operation is multiplication or division, the returned curve is a
  658.  * gamma curve with the appropriate number of points.
  659.  * Both a and b must have the same wraparound type.
  660.  * @param retval a pointer to store the location of the newly-created
  661.  * output curve in.
  662.  * @param a the first source curve.
  663.  * @param b the second source curve.
  664.  * @param mode the composition mode.
  665.  * @param points the number of points in the output curve (must not
  666.  * exceed 1048576).  It must be at least two, unless the curve is a
  667.  * gamma curve and the operation chosen is multiplication or division.
  668.  * If -1, the resulting number of points will be the least common
  669.  * multiplier of the number of points in the input and output curves
  670.  * (but will not exceed 1048576).
  671.  * @returns FALSE if element-wise composition fails.
  672.  */
  673. extern int stp_curve_compose(stp_curve_t **retval,
  674.                  stp_curve_t *a, stp_curve_t *b,
  675.                  stp_curve_compose_t mode, int points);
  676.  
  677.   /** @} */
  678.  
  679. #ifdef __cplusplus
  680.   }
  681. #endif
  682.  
  683. #endif /* GUTENPRINT_CURVE_H */
  684. /*
  685.  * End of "$Id: curve.h,v 1.1 2004/09/17 18:38:01 rleigh Exp $".
  686.  */
  687.